Skip to content

chore: release/repo hygiene, doc truth-up + drift gate, gate governance - #280

Closed
qnbs wants to merge 3 commits into
fix/openrouter-live-catalogfrom
chore/release-doc-gates
Closed

chore: release/repo hygiene, doc truth-up + drift gate, gate governance#280
qnbs wants to merge 3 commits into
fix/openrouter-live-catalogfrom
chore/release-doc-gates

Conversation

@qnbs

@qnbs qnbs commented Jul 28, 2026

Copy link
Copy Markdown
Owner

Summary

Stacked on #279 (OpenRouter). Three related hygiene workstreams:

WS-5 β€” Release & repo hygiene

  • Removed a duplicate codecov badge and the CII Best Practices badge (literal projects/XXXX placeholder β€” broken image, dead link); added a TODO.md entry with the registration URL (external signup, maintainer action).
  • Added .github/CODE_OF_CONDUCT.md (Contributor Covenant 2.1); fixed .github/CONTRIBUTING.md's external CoC link to point at it; added a missing CoC section to the root CONTRIBUTING.md (the one README.md actually links to).
  • Investigated (no code changes): the v1.5.0 GitHub release's 6 assets are all named StoryCraft.Studio_1.20.0_... β€” the pre-rebrand product name with a mismatched version, published far out of chronological order. Flagged for maintainer decision (see final report). Issue chore(security): upstream y-webrtc diff check β€” vendor fork auditΒ #60 already has a maintainer comment confirming the audit is done; no action taken, it's correctly staying open per its own "permanent reminder" note.

WS-6 β€” Doc truth-up + drift gate

  • Fixed stale "17 locales" claims (post 17β†’19 expansion) across ROADMAP.md (also still marked v1.24 "PLANNED" despite both v1.24.0 and v1.24.1 having shipped), docs/TRANSLATION-GUIDE.md (also missing desktop.json from its module list), root CONTRIBUTING.md, .github/copilot-instructions.md, and docs/i18n/AUDIT_AND_IMPROVEMENT_PLAN.md. Left every CHANGELOG.md/dated AUDIT.md/TODO.md historical entry untouched.
  • Added scripts/check-doc-metrics.mjs (pnpm run docs:check, wired into CI) β€” computes actual locale/key counts and the latest release tag, then fails if a target doc states a different number or an already-released version is still marked "PLANNED". Historical sections are exempt via a heuristic covering this repo's several "done" conventions; the exemption logic has its own test file per the plan's explicit requirement.

WS-7 β€” Gate governance

  • Re-pinned token-audit-baseline.json to the actual measured value (160, down from a stale 165) β€” ratchets down only.
  • Added scripts/check-coverage-ratchet.mjs (non-blocking, continue-on-error: true in CI) β€” suggests raising a coverage threshold when the measured value has 2+ points of headroom, mechanizing a rule that existed only as a comment in vitest.config.ts. Added the json-summary reporter so coverage-summary.json actually gets produced.
  • docs/CODE_QUALITY.md: added a Suppression Reduction Plan grouping all 33 noExplicitAny suppressions by cluster/effort (visibility only, no code changes).
  • docs/CI.md: corrected 3 places still describing Stryker as part of the active ci.yml pipeline β€” it was removed 2026-06-02 and runs only via manual workflow_dispatch.

Test plan

  • pnpm run lint / typecheck β€” clean
  • pnpm run docs:check β€” new gate passes; verified it catches injected drift (tested against a corrupted README, then reverted)
  • pnpm run token:audit β€” 160 ≀ 160 (re-pinned baseline)
  • pnpm run i18n:check / parity:check β€” unaffected, still green
  • tests/unit/checkDocMetrics.test.ts β€” 10 tests covering the historical-exclusion heuristic
  • pnpm run build && pnpm run bundle:budget β€” green
  • CI (pending)

πŸ€– Generated with Claude Code

@vercel

vercel Bot commented Jul 28, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
worldscript-studio Ready Ready Preview, Comment Jul 28, 2026 10:06pm

@coderabbitai

coderabbitai Bot commented Jul 28, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

βš™οΈ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2bd2c72f-7f1f-4b03-959d-1b192ce7725a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • βœ… Review completed - (πŸ”„ Check again to review again)
✨ Finishing Touches
πŸ§ͺ Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/release-doc-gates

Comment @coderabbitai help to get the list of available commands.

@codeant-ai

codeant-ai Bot commented Jul 28, 2026

Copy link
Copy Markdown

🏁 CodeAnt Quality Gate Results

Commit: 9425d0ef
Scan Time: 2026-07-28 21:23:53 UTC

βœ… Overall Status: PASSED

Quality Gate Details

Quality Gate Status Details
Secrets βœ… PASSED 0 secrets found
Duplicate Code βœ… PASSED 0.0% duplicated
SAST βœ… PASSED No security issues
Bugs βœ… PASSED Rating S: No bugs
IAC βœ… PASSED Rating S: No issues

View Full Results

@qnbs
qnbs force-pushed the fix/openrouter-live-catalog branch from 645d3f6 to 27016cf Compare July 28, 2026 21:26
@qnbs
qnbs force-pushed the chore/release-doc-gates branch from 96a888c to 9c1bebb Compare July 28, 2026 21:37
qnbs added 3 commits July 29, 2026 00:05
…h CONTRIBUTING files

- README.md: removed the duplicate codecov badge (kept the more informative
  `&label=Coverage` one) and the CII Best Practices badge, which had a literal
  `projects/XXXX` placeholder (broken image, dead link) β€” the project was
  never registered. Added a TODO.md entry with the registration URL; that's
  an external, interactive signup, so it stays a maintainer action, not
  something this pass does automatically.
- Added .github/CODE_OF_CONDUCT.md (Contributor Covenant 2.1), with an
  enforcement-contact section that mirrors SECURITY.md's pattern (GitHub
  Private Vulnerability Reporting, no hardcoded personal email).
- .github/CONTRIBUTING.md already referenced a Code of Conduct but linked
  externally to contributor-covenant.org instead of the new in-repo file β€”
  repointed it.
- The root CONTRIBUTING.md β€” the one README.md actually links to β€” had no
  Code of Conduct section at all. Added one, linking to the new file.

Investigated (no code changes, per the workstream's stop-and-ask boundaries):
- The v1.5.0 GitHub release sits chronologically between v1.20.0 and v1.21.0
  despite its lower semver, AND its 6 assets are all named
  "StoryCraft.Studio_1.20.0_..." β€” the project's pre-rebrand name (rebrand to
  WorldScript Studio shipped in v1.23.0) with a version that doesn't match the
  release tag at all. Flagged for the final report; deleting/retitling a
  public release is a maintainer decision.
- Issue #60 (vendor-fork audit, "permanent reminder β€” do not close") already
  has a 2026-07-28 maintainer comment documenting the audit as done, and
  `pnpm run verify:vendor` passes all 12 invariants. No action needed β€” it's
  correctly staying open per its own instruction.
… drift gate

ROADMAP.md still marked v1.24 as "(PLANNED)" though v1.24.0 (2026-06-21) and
v1.24.1 (2026-07-28) had both already shipped, and gave the locale count as
17 β€” stale since the 11->17 expansion (v1.24.0) plus ru/ko (landed the next
day, before v1.24.1). Same "17 locales" drift was independently present in
docs/TRANSLATION-GUIDE.md (also missing 1 of 21 modules β€” desktop.json β€” from
its module list and count), the root CONTRIBUTING.md (the one README.md
actually links to), .github/copilot-instructions.md (2 occurrences), and
docs/i18n/AUDIT_AND_IMPROVEMENT_PLAN.md's "current state" section. Fixed all
of them; left every CHANGELOG.md and dated AUDIT.md/TODO.md historical entry
untouched β€” they correctly describe what was true at a past release.

Added scripts/check-doc-metrics.mjs (wired into ci.yml's quality job as
`pnpm run docs:check`) so this class of drift fails CI instead of silently
accumulating again. It computes the actual locale count, key count (dedup'd
the same way check-i18n-keys.mjs does), and latest released version tag, then
scans README/ROADMAP/TODO/TRANSLATION-GUIDE/CONTRIBUTING for stale numbers or
a "vX.Y.Z ... PLANNED" claim for an already-released version.

Historical sections are exempt (Keep-a-Changelog `## [x.y.z]`, `## vX.Y.Z ...
RELEASED ...`, a heading suffixed with an emoji checkmark, a `**Status:** βœ…
Released/Completed` line just below a heading, or this repo's own TODO.md "βœ…
= done" bullet convention) β€” the first version only recognized the
Keep-a-Changelog/RELEASED-heading shapes and produced 26 false positives
against TODO.md/ROADMAP.md's other historical conventions; broadened it
before wiring the gate in. tests/unit/checkDocMetrics.test.ts covers the
exclusion heuristic directly (the plan's explicit requirement β€” an untested
exclusion rule turns a drift gate into noise).
…n, mutation-testing status

- Re-pinned token-audit-baseline.json to the actual measured total (160,
  down from a stale 165 dated 2026-06-14) after WS-1..6 landed. Ratchets
  down only, per the project's hard rule against loosening a quality gate.
- Added scripts/check-coverage-ratchet.mjs: reads coverage/coverage-summary.json
  (added the `json-summary` reporter to vitest.config.ts β€” it wasn't being
  generated at all) and suggests raising a threshold when the measured value
  sits 2+ points above it, matching the "3 green runs, max 5 pts/quarter"
  rule already documented as a comment in vitest.config.ts but never
  mechanized. Wired into ci.yml as `continue-on-error: true` β€” informational
  only, never blocks the build; the ratchet decision stays with the
  maintainer.
- docs/CODE_QUALITY.md: added a Suppression Reduction Plan grouping all 33
  noExplicitAny suppressions (of 52 total, at an exact-match baseline with
  no headroom) into clusters by root cause and effort β€” no code changes,
  visibility only.
- docs/CI.md: corrected three places that still described Stryker mutation
  testing as part of the active `ci.yml` job graph (job-graph diagram, the
  `mutation` job's table row, and the CI-tier table) β€” it was removed from
  the merge pipeline on 2026-06-02 and now runs only via manual
  `workflow_dispatch` on mutation.yml. Documented why, how to trigger it,
  and the re-integration criterion.
@qnbs
qnbs force-pushed the chore/release-doc-gates branch from 9c1bebb to aadad0e Compare July 28, 2026 22:05
@qnbs
qnbs deleted the branch fix/openrouter-live-catalog July 28, 2026 23:10
@qnbs qnbs closed this Jul 28, 2026
@qnbs

qnbs commented Jul 28, 2026

Copy link
Copy Markdown
Owner Author

This PR was auto-closed by GitHub when PR #279 merged (its base, fix/openrouter-live-catalog, was a force-pushed/rebased branch during PR #279's own CodeRabbit correction loop; GitHub couldn't cleanly retarget this PR to main and closed it instead of auto-retargeting). The branch and all its commits are intact β€” recreated as #283, now targeting main directly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant